/* Copyright (c) 2012 Nordic Semiconductor. All Rights Reserved.
 *
 * The information contained herein is property of Nordic Semiconductor ASA.
 * Terms and conditions of usage are described in detail in NORDIC
 * SEMICONDUCTOR STANDARD SOFTWARE LICENSE AGREEMENT.
 *
 * Licensees are granted free, non-transferable use of the information. NO
 * WARRANTY of ANY KIND is provided. This heading must NOT be removed from
 * the file.
 *
 * $LastChangedRevision$
 */

/** @file
 *
 * @defgroup ble_sdk_lib_bond_manager Bonds and Persistent Data Manager
 * @{
 * @ingroup ble_sdk_lib
 * @brief Module for handling multiple bonds.
 *
 * @details Applications using the Bond Manager must have a configuration file named
 *          ble_bondmngr_cfg.h (see @ref ble_sdk_apps_config_files for details).
 *
 *          The Bond Manager interacts with the BLE stack by reacting to a set of BLE stack events,
 *          thus helping the application to bond with multiple masters.
 *
 *          Sequence diagrams illustrating the flow of events when connecting to a master using the
 *          Bond Manager:
 *
 *          @image html bond_manager_unbonded_master.jpg Figure 1: Connecting to an unbonded master
 *          @n
 *          @image html bond_manager_bonded_master.jpg Figure 2: Connecting to a bonded master
 */

#ifndef BLE_BONDMNGR_H__
#define BLE_BONDMNGR_H__

#include <stdint.h>
#include "ble.h"

/**@brief Initializes the Bond Manager.
 *
 * @details On init, the Bond Manager reads the database of all bonded masters from flash.
 *          If the flash does not contain any valid data, the array of bonded masters in RAM will
 *          be emptied.
 *
 * @note Currently the Bond Manager uses only one page in flash.
 *
 * @return     NRF_SUCCESS if all operations went successfully, an error_code otherwise.
 */
uint32_t ble_bondmngr_init(void);

/**@brief  Handles all events from the BLE stack that are of interest to this module.
 *
 * @param[in]  p_ble_evt  The event received from the BLE stack.
 * @return     NRF_SUCCESS if all operations went successfully,
 *             NRF_ERROR_NO_MEM if the maximum number of bonded master has been reached.
 *             Other error codes in other situations.
 */
uint32_t ble_bondmngr_on_ble_evt(ble_evt_t * p_ble_evt);

/**@brief  Function to be called before going to system off, in order to save all bonded masters
 *         in flash memory.
 *
 * @note This operation cannot be done while the radio is in a connection or is advertising.
 *
 * @return     NRF_SUCCESS if all operations went successfully, an error_code otherwise.
 */
uint32_t ble_bondmngr_on_goto_system_off(void);

/**@brief Delete the bonded master database from flash.
 *
 * @details After calling this function you should call ble_bondmngr_init() to re-initialize 
 *          the RAM database.
 */
void ble_bondmngr_master_delete(void);

#endif // BLE_BONDMNGR_H__

/** @} */
